home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 20
/
Cream of the Crop 20 (Terry Blount) (1996).iso
/
program
/
pcl4w13.zip
/
PCL4WUSR.DOC
< prev
next >
Wrap
Text File
|
1996-07-14
|
80KB
|
2,245 lines
Personal Communications Library
For Windows
(PCL4W)
USERS MANUAL
Version 1.3
July 8, 1996
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 1996
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice : 205-881-4630
FAX : 205|880|0925
BBS : 205-880-9748
email : info@marshallsoft.com
web : www.marshallsoft.com
_______
____|__ | (R)
--+ | +-------------------
| ____|__ | Association of
| | |_| Shareware
|__| o | Professionals
--+--+ | +---------------------
|___|___| MEMBER
PCL4W Users Manual Page 1
C O N T E N T S
Chapter Page
1.0 Introduction................................................3
1.1 User Support............................................4
1.2 ASP Ombudsman...........................................4
1.3 A Typical Application...................................5
1.4 Determining UART Address & IRQ Settings.................6
1.5 Disabling Windows Ports.................................6
1.6 Installation............................................7
2.0 Library Organization........................................8
2.1 Configuration...........................................8
2.2 Initialization & Termination............................8
2.3 Modem Control & Status..................................9
2.4 Serial I/O..............................................9
2.5 Error Detection........................................10
2.6 General Support........................................10
3.0 Library Overview...........................................11
3.1 Dynamic Link Libraries.................................11
3.2 DOS Protected Mode Interface...........................11
3.3 Memory Models..........................................11
3.4 Using the Library......................................11
3.5 Using a MAKEFILE.......................................12
3.6 Using an IDE...........................................12
3.7 Making the Library.....................................12
4.0 Talking to Your Modem......................................13
4.1 Modem Standards........................................13
4.2 Flow Control...........................................14
4.3 Modem I/O Functions....................................15
4.4 Modem Initialization...................................17
5.0 Problems...................................................18
6.0 Serial Communications......................................19
6.1 Communications Basics..................................19
6.2 Standard Port Addresses................................20
6.3 Running 3 or 4 Ports Concurrently......................21
6.4 Using Multiport Boards.................................22
6.4.1 Using the Digiboard..............................22
6.4.2 Using the BOCA board.............................22
6.5 Transmitter Interrupts.................................23
6.6 RS232 Signals..........................................24
6.7 National INS8250, INS16450, and INS16550 UARTs.........25
6.8 Register Summary.......................................26
7.0 Example Programs...........................................28
7.1 SIMPLE.................................................28
7.2 LOGIN..................................................28
7.3 SELFTEST...............................................28
7.4 TERM...................................................28
8.0 Legal Issues...............................................29
8.1 Registration...........................................29
8.2 License................................................30
8.3 Warranty...............................................30
9.0 Summary....................................................31
9.1 Revision History.......................................31
9.2 Function Summary.......................................32
9.3 Further Reading........................................33
10.0 Other MarshallSoft Computing products for C/C++............33
10.1 The Personal Communications Library for C/C++.........33
10.2 Libraries for Other Languages.........................33
PCL4W Users Manual Page 2
1.0 Introduction
The Personal Communications Library for Windows (PCL4W) is an asynchronous
communications dynamic link library (DLL) for software developers using the
Microsoft Windows C/C++ compiler, the Borland Windows compiler, or the
WATCOM Windows compiler. Other Windows compilers may also work. A 80386
machine or higher is recommended.
o 30+ communications functions.
o Supports the high performance INS16550 UART.
o Supports the PC/4 and PC/8 DigiBoard.
o Supports the BOCA BB1004, BB1008, and BB2016 boards.
o Supports hardware (RTS/CTS) flow control.
o Use any IRQ (IRQ0-IRQ15) with any UART address.
o Interrupt driven receiver & (optionally) transmitter.
o Supports 300 baud to 115,200 baud.
o Supports COM1 through COM20.
o Adjustable queues from 8 bytes to 32 KB.
o Control-BREAK error exit.
o 18 communications error conditions trapped.
o Allows 4 ports to run concurrently (more with Digi/BOCA board).
o Complete modem control & status.
o Written in assembly language for small size & high speed.
o Terminal program featuring ASCII (with XON/XOFF), XMODEM,
YMODEM, & YMODEM-G.
Why should you buy PCL4W? Consider the following:
COMPLETE : PCL4W is complete since it provides absolute control of the
serial ports (including the high performance INS16550).
COMPACT : PCL4W is very compact at less than 6 KB. Your application
doesn't carry a lot of excess code.
FAST : PCL4W is fast. It will run at 115200 baud on all 80386 and
up machines.
SUPPORT : If you get stuck, you will talk to the programmer that
wrote the code, not a person hired to answer the phone.
BBS : A user support BBS is available (2400 to 14400 baud, N81) in
order to provide immediate support as necessary.
NEWSLETTER : Our newsletter "COMM TALK" is published quarterly (available
online) which discusses communications problems and
solutions.
PRICE : You get PCL4W for a very reasonable price !
UPGRADES : Once you buy PCL4W, you can always update to the most
recent version for a very reasonable cost.
COMPATIBLE : PCL4W is call for call compatible with the MSDOS based
version PCL4C except for two functions in which delay times
are no longer necessary.
Our goal is to provide a robust serial communications library that that you
and your customers can depend upon.
PCL4W Users Manual Page 3
1.1 User Support
We want you to be successful in developing your applications using PCL4W! We
depend on our customers to let us know what they need in a communications
library. This means we are committed to providing the best communications
library that we can. If you have any suggestions or comments, please let us
know.
If you are having a problem using PCL4W, call us at 205-881-4630 between
1:30PM and 9:30PM CST Monday through Friday. You can also call at other
times and leave a message, and call back later for a reply. Registered
users (ONLY) can also FAX us at 205-880-0925 at any time (24 hours).
However, we can only answer questions with respect to using the PCL4W
library. We cannot help you program your application.
You may also call our User Support BBS (2400 to 14400 baud, no parity, 8
data bits, 1 stop bit) at 205-880-9748 and leave a message (address it to
the SYSOP). We will usually have a reply ready for you within 24 hours.
The BBS is available 24 hours per day except at 2 PM Sundays for
maintenanace. All files are in standard ZIP format. The BBS will contain the
latest shareware version of all MarshallSoft products as well as related
files such as:
BUGS.ZIP: Bug report.
NEWS.ZIP: Latest news regarding our products.
If you are on the Internet, you can email us at info@marshallsoft.com. You
can also get the latest versions of our products from our anonymous ftp
site:
FTP: ftp.marshallsoft.com
PATH: marshallsoft
The MarshallSoft Computing, Inc. newsletter "Comm Talk" is published
quarterly. It discusses various communications problems and solutions using
PCL4W as well as related information.
The latest copy of our newsletter can be found on User Support BBS (in
file area "Newsletters"), our anonymous ftp site (directory /marshallsoft)
as well as our web site.
Web site: www.marshallsoft.com
1.2 ASP Ombudsman
MarshallSoft Computing, Inc. is a member of the Association of Shareware
Professionals (ASP). ASP wants to make sure that the shareware principle
works for you. If you are unable to resolve a shareware-related problem
with an ASP member by contacting the member directly, ASP may be able to
help. The ASP Ombudsman can help you resolve a dispute or problem with an
ASP member, but does not provide technical support for members' products.
Please write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI USA
49442-9427, Fax 616-788-2765, or send a CompuServe message via CompuServe
Mail to ASP Ombudsman 70007,3536.
PCL4W Users Manual Page 4
1.3 A Typical Application
In general, there are two classes of applications that use a communications
library like PCL4W: those that use a modem to connect to the outside world
and those that connect directly to a peripheral device. In either case, a
typical application program using PCL4W might consist of 3 phases:
initialization, execution, and termination. The following code segment
assumes a knowledge of the windows API.
In the following code segment, SioRxBuf is called to set up a 1024 byte
receive buffer; SioParms is called to set up the parity, stop bit count, and
word length; SioReset is called to set the baud rate to 9600 and reset the
UART (Universal Asynchronous Receiver / Transmitter).
case WM_CREATE:
/* initialization */
SioRxBuf(Port,RxBuffer,Size1024);
SioParms(Port,NoParity,OneStopBit,WordLength8);
SioReset(Port,Baud9600);
If you are using the version of the library with transmitter interrupts
enabled (PCL4W2.LIB), then SioTxBuf() must be called to set up the
transmitter buffer. The transmit buffer must be distinct from the receive
buffer.
case WM_CREATE:
/* initialization */
SioRxBuf(Port,TxBuffer,Size1024);
SioTxBuf(Port,RxBuffer,Size1024);
SioParms(Port,NoParity,OneStopBit,WordLength8);
SioReset(Port,Baud9600);
Characters can be transmitted and received once the required port is
initialized. Before leaving your application, SioDone is called to restore
the prior state of the serial communications system. Forgetting to call
SioDone before exiting your application will leave the interrupt system in
an unuseable state and the machine will have to be re-booted.
case WM_DESTROY:
/* termination */
SioDone(Port);
If you are using a modem, you also need to be concerned about initializing
your modem correctly and handling any required flow control. Refer to
Chapter 4.0, "Talking to Your Modem" for detailed information.
PCL4W Users Manual Page 5
1.4 Determining UART Address & IRQ Settings
Both Windows 3.X and Windows 95 maintain a list of serial port settings. On
Windows 3.X systems, choose the "Ports" icon in the "Control Panel" in the
"Main Group". Select "Settings", and then "Advanced" to view the COM port
UART address and IRQ settings.
In Windows 95, choose "My Computer" icon ("or whatever your computer icon is
named), select the "Control Panel" folder and then the "System" icon. Click
on the "Device Manager" tab. Click "Computer" and then click "Properties".
Click the "View Resources" tab. To view reserved resources, click the
resource type at the top of the dialog box (i.e., "Interrupt request (IRQ)"
or "Input/output (I/O)" ).
1.5 Disabling Windows Ports
The Windows operating system virtualizes all serial ports that it controls.
This means that Windows intercepts reads and writes to hardware ports,
resulting in significant slowdown. When Windows virtualizes a port, the UART
FIFO control register (FCR) can not be modified.
Since PCL4W also controls the hardware directly, it is best (although not
absolutely necessary) to disable Windows control of the serial ports and the
IRQs that will be used by PCL4W applications.
The four standard COM ports which Windows typically controls are:
Port Address IRQ
COM1 &H3F8 4
COM2 &H2F8 3
COM3 &H3E8 4
COM4 &H2E8 3
Since COM1 and COM3 share an IRQ, if either is to be used by PCL4W then both
should be disabled from Windows control. Similarly for COM2 and COM4.
To begin, exit from Windows completely. To disable the serial ports, edit
the [386Enh] section of the WINDOWS.INI file in the WINDOWS directory. For
example, to disable COM1 and COM3, add the following to the [386 Ehn]
section:
COM1Base=0
COM1Irq=-1
COM3Base=0
COM3Irq=-1
Restart Windows after modifying SYSTEM.INI. This procedure does not apply to
multiport boards or any other serial ports unknown to Windows.
16550 UARTS are really necessary when running under Windows, particularly at
baud rate above 19200. The Microsoft Diagnostics (MSD) program can be run
which will report the type of UARTs installed on your machine.
If a 16550 port MUST be shared with Windows, and you want the FIFO enabled,
look for statements such as
COM1FIFO=0
in the [386Ehn] section of SYSTEM.INI and delete it. However, the Windows
communications driver may have trouble with the FIFO, which is why there is
a statement to disable it. This problem does not occur with PCL4W.
PCL4W Users Manual Page 6
1.6 Installation
(1) Before installation of PCL4W , your Windows C compiler should already be
installed on your system and tested. Examine the file "FILES.LST" for a list
of the distribution files.
(2) Make a backup copy of your distribution disk. Put your original
distribution disk in a safe place.
(3) Create a work directory on your hard drive. For example, to create a
work directory named PCL4W, type from DOS:
MKDIR PCL4W
(4) Copy all the files from your backup copy of the distribution disk to
your work directory. For example, to copy from the A: drive to your work
directory, we type:
CD PCL4W
COPY A:*.*
(5) Compile SIMPLE.C and link with the PCL4W library (PCL4W.LIB).
Makefiles and project files are provided for each of the supported
compilers.
Microsoft command line compiler: NMAKE SIMPLE._M_
Borland command line compiler: MAKER -fSIMPLE._B_
Watcom command line compiler: WMAKE -f SIMPLE._W_
NOTES: (1) Use NMAKE, not MAKE with Microsoft C
(2) Use MAKER, not MAKE with Borland C.
Alternately, SIMPLE can be compiled in an Integrated Development Environment
(IDE) such as supplied by Microsoft, Borland, and Watcom. Refer to section
3.5 "Using an IDE" for more information.
(6) The recommended way to test SIMPLE is to run it on two computers
connected by a null modem cable. Whatever is typed on one computer should
be displayed on the other. If you don't have two computers, you can use
SIMPLE to talk to your modem. Sending an "AT" to the modem should result in
an "OK" being sent back. See section 7.1 "SIMPLE" for more information.
(7) Compile and link LOGIN. Use LOGIN to call a local BBS. See section 7.1
"LOGIN" for more information.
(8) Compile and link SELFTEST. Use SELFTEST to test one of your serial
ports. See section 7.3 "SELFTEST" for more information.
PCL4W Users Manual Page 7
2.0 Library Organization
The PCL4W library is organized into six categories of functions. Refer to
the PCL Reference Manual (PCL4W.REF) for details on individual functions.
2.1 Configuration
There are three functions in the configuration category. SioPorts sets the
number of PC and DigiBoard / BOCA ports. SioUART is used to change the UART
base address for a communications port to a non-standard address, while
SioIRQ is used to assign a nonstandard IRQ line to a port. (See Section
6.2, Standard Port Addresses for more details on standard UART addresses and
IRQ lines).
The configuration functions SioPorts, SioUART and SioIRQ must be called
before calling any other library functions. Be very careful when using
these functions. Remember that your serial hardware must support the UART
and IRQ that you specify. Always test any new configuration immediately.
SioPorts : Sets number of PC and DigiBoard / BOCA ports.
SioUART : Sets the UART base address.
SioIRQ : Assigns an IRQ line to a port.
THE IRQ GOLDEN RULE: You may open (via SioReset) only one port per IRQ
(except for the DigiBoard / BOCA board).
2.2 Initialization & Termination
There are nine functions in the initialization and termination category.
Together, SioGetDiv, SioFIFO, SioRxBuf, SioTxBuf, and SioReset initialize
your serial communications system. Your application must call SioParms and
SioRxBuf before calling SioReset, and SioReset must be called before any
serial I/O processing can be done.
After initialization, SioParms and SioBaud can be called again to change the
communications parameters without resetting the serial port. SioFlow can be
called to enable hardware flow control.
Before exiting from your application, SioDone must be called. Failure to
call SioDone can crash your system later.
SioRxBuf : Sets up receive buffer.
SioTxBuf : Sets up transmitter buffer.
SioFIFO : Sets the interrupt level for the INS16550.
SioParms : Sets parity, stop bits, and word length.
SioReset : Initialize a serial port for processing.
SioDone : Terminates further serial processing.
SioBaud : Sets the baud rate of the selected port.
SioFlow : Enables / disables flow control.
SioGetDiv : Gets the baud rate divisor.
PCL4W Users Manual Page 8
2.3 Modem Control & Status
There are eight functions in the modem control and status category which
provide your application with complete control over the status and control
bits of your modem.
There are two modem control bits, "Data Terminal Ready" (DTR) and "Request
To Send" (RTS). These bits can be read, set, or cleared by SioDTR and
SioRTS.
There are four modem status bits, "Data Set Ready" (DSR), "Clear To Send"
(CTS), "Ring Indicator" (RI), and "Data Carrier Detect" (DCD). SioModem can
read any of the modem status bits. SioDSR, SioCTS, SioRI, and SioDCD can
only read their respective modem status bit.
Refer to the chapter entitled "RS232 Signals" for a discussion of each of
the control and status bits.
SioDTR : Set, clear, or read the Data Terminal Ready (DTR) bit.
SioRTS : Sets, clears, or reads the Request to Send (RTS) line.
SioModem : Reads the modem status register.
SioDSR : Reads the Data Set Ready (DSR) modem status bit.
SioCTS : Reads the Clear to Send (CTS) modem status bit.
SioDCD : Reads the Data Carrier Detect (DCD) modem status bit.
SioRI : Reads the Ring Indicator (RI) modem status bit.
SioRead : Reads the contents of the 7 UART registers.
2.4 Serial I/O
There are eight library functions in the serial I/O category. Together,
these functions give the programmer complete control over serial I/O. Higher
level functions such as protocols and smart modem communications can be
completely implemented in terms of these functions. Refer to the example
code.
SioGetc and SioPutc perform all the actual serial I/O. SioUnGetc "ungets"
the last serial byte read. SioRxClear clears the receive queue while
SioTxClear clears the transmit queue. SioLine can be used to test for UART
errors. SioRxQue returns the number of bytes in the receive queue while
SioTxQue returns the number of bytes in the transmit queue.
SioGetc : Reads the next character from the serial line.
SioPutc : Transmit a character over a serial line.
SioUnGetc : "Un:gets" (puts back) a specified character.
SioRxClear : Flush (clears) the receive buffer.
SioRxQue : Returns the number of characters in the RX queue.
SioTxClear : Flush (clears) the transmit buffer.
SioTxQue : Returns the number of characters in the TX queue.
SioLine : Reads the line status register.
PCL4W Users Manual Page 9
2.5 Error Detection
There are three functions in the error detection category. They are
concerned with detecting or reporting communications errors. Use of these
functions can make your application significantly more robust.
SioBrkSig can read or modify the UART break bit. This is useful for
signalling the remote system that a fatal condition has occurred.
SioLoopBack can be used to test the integrity of your UART.
There is also a file SIOERROR.C which contains the function SioError which
displays a error message corresponding to an error code returned from a
PCL4W function (every PCL4W function returns a code).
SioBrkSig : Asserts, cancels, or detects the RS232 BREAK signal.
SioError : Displays error in text.
SioLoopBack : Performs a UART loopback test.
2.6 General Support
There is one function in the general support category. SioInfo returns the
version number of the library and whether transmitter interrupts are
enabled.
SioInfo : Returns the library version, memory model, the number of
transmitter interrupts, and receiver interrupts.
PCL4W Users Manual Page 10
3.0 Library Overview
3.1 Dynamic Link Libraries
PCL4W is provided as a dynamic link library (DLL). A DLL is characterized by
the fact that it need not be loaded until required by an application program
and that only one copy of the DLL is necessary regardless of the number of
application programs that use it. Contrast this to the traditional static
library which is bound to each and every application that uses it at link
time.
Since PCL4W is a DLL, only one copy of the PCL4W code & data is loaded into
memory regardless of the number of applications programs that use it.
For example, more than one instance of the test program SIMPLE can be
started. All copies of SIMPLE can run concurrently as long as each uses a
different COM port.
3.2 DOS Protected Mode Interface
Windows itself uses what is known as the "DOS Protected Mode Interface"
(DPMI) to control changing states (protected vs real), controlling the
interrupt system, etc. This is necessary because Windows itself typically
runs in a protected state and must change to real state in order to use
MSDOS services.
The PCL4W library uses this same DPMI mechanism. In particular, the file
USE_DPMI.ASM contains the necessary functions for using DPMI. The developer
should not modify USE_DPMI.ASM in any way.
3.3 Memory Models
Most windows programs are small or medium memory model programs since these
memory models are limited to one data segment. However, all PCL4W functions
are FAR functions, so they can be used with any memory model. Thus, there is
just one PCL4W.DLL and PCL4W.LIB regardless of the memory model used.
3.4 Using the Library
The PCL4W has been tested on a Gateway 2000 25 MHZ 80386-DX, a Gateway 2000
66MHZ 80486-DX2 (all running Windows 3.1), and a Mid-West Micro 150MHZ
Pentium running Windows 95.
PCL4W has been testing with the Microsoft Windows SDK compiler, Visual
C/C++, Borland C/C++, and Watcom C/C++.
Please examine the PCL4W.H file. Note that COM1 is defined as port zero, not
port one. The user must assume the responsibilty for passing the correct
information when calling PCL4W functions.
If there are any conflicts between PCL4W definitions and those in other
libraries, the PCL4W definitions can be changed in the PCL4W.H file and any
file that uses the definition. There is no change necessary for the library
code itself.
If you write an application using the PCL4W library, don't run another
application that uses the same communications port.
PCL4W Users Manual Page 11
3.5 Using a MAKEFILE
Makefiles originated on UNIX systems. They are the standard way that C/C++
programs are constructed in command line environments. Windows programs can
be constructed with makefiles running DOS using command line Windows
compilers, such as provide by Borland and Microsoft.
Makefiles are provided for Microsoft and Borland command line compilers.
3.6 Using an IDE
All windows comilers have an Integrated Development Environment (IDE) for
building application programs in the Windows environment. Since there is no
standard format for IDE project files, file names must be entered into the
IDE from the keyboard. Each example program has a project text file (eg:
SIMPLE.PRJ) which contains the list of filenames that must be entered into
the IDE.
The example programs have been build using Microsoft, Borland, and Watcom
IDEs. Refer to IDE_INFO.DOC for more information on using specfic IDEs.
3.7 Making the Library
Registered users may wish to assemble PCL4W.ASM. Use the /MX switch in
order to disable automatic conversion from lower case to upper case. If the
/MX switch is not used, then all PCL4W function references in C code must be
in upper case. To assemble using the Microsoft assembler, use the provided
makefile "PCL4W.MAK". From the DOS command line, type
nmake pcl4w.mak
Two libraries are made, one with transmitter interrupts disabled (PCL4W1)
and one with transmitter interrupts enabled (PCL4W2). Most users should use
the library without transmitter interrupts enabled since they require less
overhead.
To use the PCL4W qlibrary without transmitter interrupts enabled, type
copy pcl4w1.lib pcl4w.lib
copy pcl4w1.dll pcl4w.dll
To use the PCL4W library with transmitter interrupts enabled, type
copy pcl4w2.lib pcl4w.lib
copy pcl4w2.dll pcl4w.dll
After creating PCL4W.LIB and PCL4W.DLL, the example programs can be compiled
and linked. Refer to Chapter 7.0, "Example Programs".
PCL4W Users Manual Page 12
4.0 Talking to Your Modem
A modem is used to extend the distance over which you may communicate.
Without a modem, your RS232 cable is limited to a maximum of approximately
50 feet. But with a modem, you can communicate literally around the world.
4.1 Modem Standards
Two modems can communicate over a telephone line only if they are both using
the same signaling frequencies and modulation, which are determined by the
the modem standards used. Modem standards can be divided into three sets:
(1) speed, (2) data compression used, and (3) error control.
The Bell standards (103 & 212A) are those of AT&T. The CCITT (The
International Consultative Committee for Telephone and Telegraph) standards
are designated as "V. ".
Speed
Bell 103 : 300 baud
Bell 212A : 1200 baud
V.21 : 300 baud
V.22bis : 1200 & 2400 baud
V.32 : 4800 & 9600 baud
V.32bis : 4800, 7200, 9600, 12000, and 14400 baud
Data Compression
MNP 5 : Microcom Networking Protocol (proprietary).
V.42bis : International data compression standard.
Error Control
MNP 2,3,4 : Three level error correction (public domain).
V.42 : International error correction standard.
PCL4W Users Manual Page 13
4.2 Flow Control
With modems using data compression, the modem to modem connection will run
at various speeds depending on the quality of the line. The computer to
modem connection will be at a fixed baud rate. Therefore, a protocol (flow
control) is necessary to synchronize the data flow between a modem and the
computer to which it is connected. Refer to your modem manual for
information on flow control protocols supported.
Two flow control protocols are used by most all modems which require flow
control. Software flow control is called "XON/XOFF" (other software flow
control character pairs are defined but operate the same as XON/XOFF) and
hardware flow control is called "RTS/CTS". Most modems which require flow
control enable hardware flow control by default.
In XON/XOFF (software) flow control, the computer suspends transmitting data
if it receives a XOFF character (13 hex) from the modem, and continues
transmitting when it receives a XON character (11 hex). Similiarly, the
computer can signal the modem not to send any more data by transmitting a
XOFF to it, and can tell the modem to continue transmission be sending a
XON.
In RTS/CTS (hardware) flow control, the RTS line is used by the computer to
signal the modem , while the CTS line is used by the modem to signal the
computer. The RTS line is set OFF by the computer to tell the modem to
suspend transmission, and set to ON to tell the modem to continue
transmission. The CTS line is set to OFF by the modem to tell the computer
to stop transmitting, and set to ON to tell the computer to continue
transmitting.
Given the choice, always choose hardware flow control over software flow
control so that all data transmission is transparent. If hardware flow
control is not the default (which it almost always is), you should modify
your modem initialization string to turn hardware flow control on.
PCL4W Users Manual Page 14
4.3 MODEM I/O (MIO)
4.3.1 MIO Introduction
The file MIO.H contains declarations for using the Modem I/O DLL. These
functions ease communicating with modems using AT commands. The LOGIN
example program code has examples of using the MIO functions.
The Windows "operating system" is what is called "cooperative multitasking".
This means that the executing Windows task must voluntarily "give up"
control before another Windows task (or Windows itself) can execute.
The difficulty is how to wait for a number of seconds while still
relinquishing control periodically before the wait is up. One solution is by
making functions that need to wait (such as the MIO functions) into "state"
machines. A function is broken down into parts called states, and control is
returned to Windows between executing each state.
For example, to send the string "ATDT1,205,880,9748" to the modem with one
tenth second delay between transmitted characters, the following sequence is
used:
(1) Send the string to the MIO driver by executing:
Code = mioSendTo(Port,100,"!ATDT1,205,880,9748")
The '!' characters are converted to carriage returns. The text string is
copied into the driver's data area.
(2) Call mioDriver (typically based on a timer) until MIO_IDLE is returned.
Each time mioDriver is called, it will send another character to the modem
provided the required delay (since the previous character was sent) has
passed. If the delay has not passed, the driver simply returns MIO_RUNNING,
but without actually sending a character to the modem. Once all characters
have been sent, mioDriver will return MIO_IDLE, indicating it is done and is
ready to accept another function.
mioDriver will return MIO_RUNNING if it is still processing. Anything else
received indicates that it is still processing and the returned value is a
character from the modem that can be displayed if wanted.
(3) Once mioDriver returns MIO_IDLE, call mioResult to get the result of the
mioSendTo call.
The above is rather straight forward in practice. See the LOGIN application
for an example of its use.
4.3.2 MIO Functions
4.3.2.1 mioDriver
Syntax: int mioDriver(int Port)
mioDriver executes the next state of any previously started MIO function
such as mioSendTo, mioWaitFor, and mioQuiet. It returns:
MIO_IDLE : if the driver is ready for the next mioSendTo, mioWaitFor, or
mioQuiet.
MIO_RUNNING : if the driver is not idle.
<otherwise> : if the driver is not idle, and the returned character was
received from the modem.
PCL4W Users Manual Page 15
4.3.2.2 mioBreak
Forces the MIO driver to the IDLE state, abandoning any work in progress.
4.3.2.3 mioSendTo
Syntax: int mioSendTo(int Port, long Pace, char *String)
The mioSendTo function sends the characters in the string 'Text' to serial
output. There is a delay of 'Pace' milliseconds between characters.
4.3.2.4 mioWaitFor
Syntax: int mioWaitFor(int Port, long Wait, int Case, char *String)
The mioWaitFor function waits for characters from serial input that match
the string 'Text'. A total of 'Wait' milliseconds are allowed before timing
out and returning FALSE (0). If the 'Case' flag is TRUE, then the string
comparison is NOT case sensitive.
For example, to wait up to one minute for "CONNECT", "NO CARRIER", or "BUSY"
from the modem after dialing a number (on COM1):
Code = mioWaitFor(COM1,60000,1,"CONNECT|NO CARRIER|BUSY")
The function mioDriver() must be called until MIO_IDLE is returned. Then
mioResult() is called to get the result of the mioWaitFor. A value of 0
indicates that neither "CONNECT", "BUSY", nor "NO CARRIER" was received. A
non-zero value indicates that one of the three sub-strings was received. A
ASC("0") is returned if "CONNECT" was seen, ASC("1") is returned if "NO
CARRIER" was seen, and ASC("2") is returned if "BUSY" was seen.
4.3.2.5 mioQuiet
Syntax: int mioQuiet(int Port,long Wait)
The mioQuiet function waits for continuous quiet [no incoming serial data]
of 'Wait' milliseconds before returning. Any incoming character while
mioQuiet us running is flushed.
4.3.3 MIO Summary
mioDriver : Allows the execution of mioSendTo, mioWaitFor, or
mioQuiet once they have been started. Returns MIO_IDLE
(defined in MIO.H) if ready not running, MIO_RUNNING if
running, and anything else is a character from the modem
that can be displayed if wanted.
mioBreak : Forces the MIO driver to IDLE state.
mioSendTo : Sends string (including control chars) to the modem.
mioWaitFor : Waits for a particular string from the modem, passing
all else through.
mioQuiet : Waits for continuous quiet of specified duration.
mioBreak : Breaks further modem I/O activity.
PCL4W Users Manual Page 16
4.4 Modem Initialization
If your application uses a modem (as opposed to using a null modem cable),
then you should always send an initialization string to your modem if it is
a programmable modem such as those made by Hayes. Communication programs
such as PROCOMM and TELIX always send such a string automatically as soon as
they start up.
The particular initialization string depends on the make of your modem. For
Hayes and Hayes AT command set compatible modems, the following string
(followed by a carriage return) should work:
AT E1 S7=60 S11=60 V1 X1 Q0 S0=0
Refer to your Modem User's Guide for a full discussion of these commands. A
brief description is as follows:
AT Modem attention command.
E1 Modem will echo what you send to it.
S7=60 Wait 60 seconds for carrier and/or dial tone.
S11=60 Use 60 milliseconds for tone dialing duration & spacing.
V1 Display result code as words (not numbers).
X1 Use the extended result message (CONNECT XXXX) set.
Q0 Modem returns result codes.
S0=0 Do not answer RING.
If your application will answer incoming calls, then set the S0 register to
the ring on which to automatically answer.
If you send the above codes by using SioPutc (as opposed to typing them from
the keyboard), then follow these guidelines:
(1) Send an initial carriage return before the initialization string.
(2) Pause at least 150 milliseconds after each character sent as your modem
needs the time to perform its own internal processing. Pause a little longer
if your modem is not accepting your initialization string.
(3) Pause one and a half seconds after sending any initialization command
such as ATZ or AT&F since your modem must do quite a bit of processing.
If you experience any problems in initializing your Hayes modem, you should
first reset it to factory settings by sending:
AT&F
Refer to the LOGIN program (function SendToModem in the file MODEM_IO.C) for
an example of sending an initialization string to a Hayes compatible modem.
PCL4W Users Manual Page 17
5.0 Problems
If you cannot get your application to run properly, first compile and run
the terminal emulator program SIMPLE provided on your distribution disk.
Test SIMPLE by connecting two computers with a null modem cable or by
commanding a Hayes AT command set compatible modem.
Once SIMPLE runs, compile and run the SELFTEST program. This program will
test your serial ports functionality.
If your application does not run but SIMPLE and SELFTEST run correctly,
then you have most likely made a programming mistake in your application.
MarshallSoft Computing cannot debug your application, especially over the
telephone! However, consider each of the following when searching for an
error in your application.
1. Have you included the file PCL4W.H in your application ?
2. Is your receive buffer large enough ? If you are using 1K data blocks in
YMODEM, then your receive buffer should be at least 1K (2K if baud rates
above 19200 are to be used).
3. Have you selected too high a baud rate? Windows can multitask many tasks
at once. You may have to lower your baud rate (or get 16550 UARTS).
4. If you are running two COM ports simultaneously, are you using separate
receive and transmits buffers ? (you should).
5. Did SioReset return a zero value ? If not, then you must call SioReset
again. See LOGIN.C for an example.
6. Did you send the proper initialization string to your modem ? Did you
set DTR and RTS ? (you should).
7. Do you have more than one COM1 port? For example, if you have a COM1
port on your motherboard, you cannot add another COM1 port or modem board
that uses COM1 without first disabling the COM1 on the motherboard.
8. Is your IRQ set correctly? If you can transmit data but can't receive
using the PCL4W library with transmitter interrupts disabled (PCL4W2), then
this usually means that interrupts are not working.
9. If -19 is returned from SioReset, this means that you have not called
PostMainHandle() from within your code first. See example in SIMPLE.C.
We recommend the following steps if you believe that you have discovered a
bug in the library: (1) Create the smallest, simpliest test program
possible that demonstrates the problem. (2) Document your exact machine
configuration and what error the test program demonstrates. (3) Upload
the example source to our user support BBS, email it or mail us a disk.
If the problem can be solved with an easy work-around, we will publish the
work-around. If the problem requires a modification to the library, we will
make the change and make the modified library available to our customers
without charge.
PCL4W Users Manual Page 18
6.0 Serial Communications
6.1 Communications Basics
The heart of serial communications is the UART (Universal Asynchronous
Receiver Transmitter). The IBM PC/XT/AT and compatibles use the 8250,
16450, or the 16550 UART. The purpose of the UART is:
(1) To convert bytes from the CPU (Central Processing Unit), into a serial
format by adding the necessary start, stop, and parity bits to each byte
before transmission, and to then transmit each bit at the correct baud rate.
(2) To convert the incoming stream (at a specified baud rate) of serial bits
into bytes by removing the start, stop, and parity bits before being made
available to the CPU.
The UART is part of the serial interface circuitry which allows the CPU to
send and receive signals over the RS232 lines. This can be diagrammed as
follows:
Serial Interface
+-------------------+
| |
+-----+ Data Bus | +------+ | RS232 Signals
| CPU +------------+ | UART | +----------------*
+-----+ | +------+ |
| |
+-------------------+
The 8250/16450/16550 UART is capable of operating in one of two modes,
"polled" and "interrupt driven". The serial communications functions in the
BIOS uses the polled method. In this approach, the CPU is typically in a
loop asking the UART over and over again if it has a byte ready. If its
does, the polling code returns the byte. But, if the next byte comes in
before the polling code is executing again, then that byte is lost.
In the interrupt driven approach (used by PCL4W), when a byte is received by
the UART, an "Interrupt Service Routine" (ISR) is executed immediately,
suspending temporarily whatever else is executing. The ISR then moves the
byte to a buffer so that your application program can later read it.
If transmitter interrupts are enabled, then bytes are queued up waiting
transmission. When a byte is moved from the UART transmitter holding
register to the UART transmitter shift register, an interrupt is generated
and the next byte is taken from the library transmitter buffer by the ISR
and written to the UART holding register.
Up to 16 bytes can be taken from the transmitter buffer while processing one
transmitter interrupt if an 16550 UART is used. The 16550 UART is strongly
recommended for computers doing serial communications under Windows.
Refer to Sections 6.6 and 6.7 entitled "RS232 Signals" and "National
INS8250, INS16450, and INS16550 UARTs", respectively for further
information on these topics.
PCL4W Users Manual Page 19
6.2 Standard Port Addresses
There are a few things to know about how serial communications ports are
used by IBM PC/XT/AT and compatible computers. The standard IBM PC/XT/AT
configuration values are as follows:
Port Reg Base IRQ Line Vector
COM1 3F8H 4 12
COM2 2F8H 3 11
COM3 3E8H 4 12
COM4 2E8H 3 11
(Refer to your DigiBoard manual for DigiBoard addresses, and your BOCA
manual for BOCA board addresses).
PCL4W assumes the above values. If necessary, the UART base address can be
changed by SioUART, and IRQ lines can be re-assigned by SioIRQ. Remember
that each port to be used concurrently must have a unique IRQ line. Refer
to the PCL4W Reference Manual for specific details.
When installing new communications cards, the following guidelines are
recommended:
(1) Be sure to read the documentation for the hardware you are installing.
Pay special attention to UART base addresses and IRQ lines, particularly if
trying to set up a non-standard configuration.
(2) If you have a choice in base addresses and IRQ lines, always choose
standard values as defined above.
(3) The first port should be COM1, the second COM2, etc.
(4) Use SioUART to zero all unused ports (for example, call SioUART(COM4,0)
if there is no COM4 port installed).
(5) Be carefull not to configure two ports for the same address. This is
easier to do than you may believe.
(6) Choose an external modem over an internal one. It is much easier to
debug problems with an external modem than an internal one.
(7) Select hardware flow control (RTS/CTS) if flow control is required and
hardware flow control is not the default.
(8) Always test your port as soon as it is installed. Try several programs
that use the communications ports.
PCL4W Users Manual Page 20
6.3 Running 3 or 4 Ports Concurrently
PCL4W supports up to 4 serial ports running concurrently (more if you have a
DigiBoard or BOCA board). One free interrupt for each port is required.
Refer to the next section if you have a DigiBoard or BOCA board.
Interrupts IRQ4 and IRQ3 are dedicated to the communications ports in a
standard IBM PC/XT/AT configuration. IRQ4 is shared between COM1 and COM3
while IRQ3 is shared between COM2 and COM4. This means that you can run two
ports simultaneously provided that they don't share an interrupt.
Suppose that you wish to run 3 ports simultaneously. To begin, you must have
3 serial UARTs installed on your computer. Assume, for purposes of this
discussion, that COM1 is installed on your motherboard, and that you have
purchased a new 2 port serial communications board.
You should be able to configure the first serial board port as COM2, which
uses IRQ3. Refer to the manual that came with your serial board.
In order to run the third serial port concurrently with the first two, an
unused interrupt must be found. If your serial card can use only IRQ3 and
IRQ4, then there is no way to run a third line since IRQ4 and IRQ3 are used
for COM1 and COM2.
However, many serial cards can use other IRQs, typically IRQ2 through IRQ7.
Since IRQ5 is normally used for a second printer port, it is a good
candidate for COM3. To use IRQ5 for the third serial port, first set your
serial card to use IRQ5 for COM3 (refer to your serial card manual) and then
add the following line to your applications code before calling SioReset:
SioIRQ(COM3,IRQ5);
Don't forget to disable any device that might use IRQ5, such as a second
printer port or a music card. Unfortunately, there is no easy way to
determine that you have no conflicts until you actually attempt to use the
IRQ. If there are conflicts, your system will probably hang and you will
have to reboot.
To run a fourth serial port, another free IRQ must be found. On some
systems, IRQ7 can be used. You must first disable IRQ7 on your parallel port
card first (your printer doesn't need an IRQ). To use IRQ7 for the fourth
serial port, first set your serial card to use IRQ7 for COM4 and then add:
SioIRQ(COM4,IRQ7);
To summarize, your serial card must be able to generate the correct IRQ,
which is not already being used. Refer to the entry for the SioIRQ function
in the PCL4W Reference Manual.
PCL4W Users Manual Page 21
6.4 Using Multiport Cards
The PCL4W library supports the dumb Digiboard (PC/4 and PC/8) and the dumb
BOCA board (BB1004, BB1008, and BB2016). Most multiport boards will be
compatible with either the DigiBoard (the status register contains the port
number), or the BOCA board (the status register is bit mapped).
6.4.1 The DigiBoard
In order to use the DigiBoard, (not the Intelligent Digiboards such as the
PC/Xe and PC/Xi) you must configure PCL4W using the SioPorts(), SioUART(),
and SioIRQ() functions.
Your PCs ports must be partitioned into "standard" PC ports and dumb card
ports. Remember that standard PC ports cannot share IRQs like the DigiBoard
(or BOCA board) can. If you are using IRQ4 and IRQ3 for standard PC ports
COM1 and COM2, then you cannot use either for DigiBoard ports (try IRQ5 or
IRQ7).
Suppose that COM1 through COM2 are standard PC ports (using IRQ4 and IRQ3)
and you have installed a PC/8 DigiBoard that you wish to use for COM3
through COM10 using interrupt line IRQ5. You choose to use the recommended
DigiBoard UART addresses starting at 0x100:
SioPorts(10,COM3,0x140,DIGIBOARD);/* COM3 = 1st DigiBoard port */
Address = 0x100; /* 1st DigiBoard UART address */
for(Port=COM3;Port<=COM10;Port++) /* look at each port */
{SioUART(Port,Address); /* set the UART address */
Address += 8; /* compute next address */
SioIRQ(Port,IRQ5); /* set the DigiBoard IRQ */
}
The DigiBoard uses 0x140 for the status address for odd interrupts and 0x141
for even interrupts.
Digiboard may be contacted at 6400 Flying Cloud Drive, Eden Prairie, MN
55344. Telephone 612-943-9020 or FAX 612-943-5398.
6.4.2 The BOCA Board
In order to use the dumb BOCA Boards, you must configure PCL4W using the
SioPorts(), SioUART(), and SioIRQ() functions.
For example, to configure the BOCA BB2016 to use COM1 to COM16, with base
addresses starting at 0x100 and IRQ5:
SioPorts(16,COM1,0x107,BOCABOARD);/* COM3 = 1st BOCA board port */
Address = 0x100; /* 1st BOCA UART address */
for(Port=COM1;Port<=COM16;Port++) /* look at each port */
{SioUART(Port,Address); /* set the UART address */
Address += 8; /* compute next address */
SioIRQ(Port,IRQ5); /* set the BOCA IRQ */
}
BOCA may be contacted at BOCA Research, Inc., 6413 Congress Avenue, Suite
130, Boca Raton, FL 33487. Phone 407-241-8088, FAX 407-997-0918.
PCL4W Users Manual Page 22
6.5 Transmitter Interrupts
Transmitter interrupts are supported by the library. Separate libraries are
provided, one with transmitter interrupts enabled and one without. When
transmitter interrupts are NOT enabled, the following logic occurs every
time you call SioPutc():
1. Wait for transmit buffer to become empty. The transmit buffer may not
be empty if the previous transmit is not completed (the UART breaks down the
byte & sends 1 bit at a time). 2. When the transmit buffer is empty, the
byte from the SioPutc() call is loaded into the transmit buffer and control
is returned to the caller.
Note that you can not write to the UART any faster the the UART baud rate.
When transmitter interrupts are enabled, the byte from SioPutc() is put into
a previously prepared (by SioTxQue) transmitter queue. The interrupt service
routine fetches bytes from this queue as soon as the previous byte has been
sent.
While you can now call SioPutc() faster than the baud rate, bytes are still
transmitted at the given baud rate.
The above sounds like transmitter interrupts are the way to go.
Unfortunately, this is usually NOT the case. Most applications will perform
better if transmitter interrupts are NOT enabled.
The reason is that transmitter interrupts double the amount of code in the
time critical interrupt service routine. While the library is processing a
transmitter interrupt (which can take a while), incoming bytes can not be
processed. What this means is that a given machine can run at a higher baud
rate without transmitter interrupts. This problem is compounded when running
multiple ports simultaniously.
However, there are a few application areas where transmitter interrupts are
preferable. If your application will be transmitting blocks of data at
fairly slow baud rates you might profit from enabling transmitter interrupts
provided that there is something else for the processor to do (which is NOT
the case in most protocols).
However, if you are using 16550 UARTS (which have 16 byte on-chip transmit
and receive buffers rather that the 1 byte buffers on the 8250 and 16450
UARTS), you may want to use the library version with interrupts enabled
provided that you enable the 16550 UART with the SioFIFO() function.
PCL4W Users Manual Page 23
6.6 RS-232 Signals
RS-232 is the name of the serial data interface standard used to connect
computers to modems. Most IBM compatible computers are built with at least
one serial port and use either DB9 (9 pin) or DB25 (25 pin) connectors.
A summary of these pins and their function follows. For more detailed
information, refer to one of the many books dealing with RS-232 interfacing.
Signal Ground Pin 7 (DB25), Pin 5 (DB9)
The SG line is used as the common signal ground, and must always be
connected.
Transmit Data Pin 2 (DB25), Pin 3 (DB9)
The TX line is used to carry data from the computer to the modem.
Receive Data Pin 3 (DB25), Pin 2 (DB9)
The RX line is used to carry data from the modem to the computer.
Data Terminal Ready Pin 20 (DB25), Pin 4 (DB9)
The DTR line is used by the computer to signal the modem that it is ready.
DTR should be set high when talking to a modem.
Data Set Ready Pin 6 (DB25), Pin 6 (DB9)
The DSR line is used by the modem to signal the computer that it is ready.
Request to Send Pin 4 (DB25), Pin 7 (DB9)
The RTS line is used to "turn the line around" in half duplex modems, and
for hardware flow control in most modems that require flow control. RTS is
controlled by the computer and read by the serial device (modem).
Clear to Send Pin 5 (DB25), Pin 8 (DB9)
The CTS line is used to "turn the line around" in half duplex modems, and
for hardware flow control in most modems that require flow control. CTS is
controlled by the serial device (modem) and read by the computer.
Data Carrier Detect Pin 8 (DB25), Pin 1 (DB9)
The DCD line is used by the modem to signal the computer that a data carrier
signal is present.
Ring Indicator Pin 22 (DB25), Pin 9 (DB9)
The RI line is asserted when a 'ring' occurs.
PCL4W Users Manual Page 24
6.7 National INS8250, INS16450, and INS16550 UARTs
The Personal Communications Library is based on the standard National
INS8250, INS16450, and INS16550 UARTs. The 8250 was the original UART used
in the IBM PC, whereas the 16450 is a faster version found on most 286 & up
machines. The 16550 contains a 16 byte FIFO to further reduce communications
overhead. These UARTs consists of 8 register ports as follows:
Offset R/W Register
0 R/W Receiver (read) / Transmitter (write)
1 R/W Interrupt Enable (read)
2 R Interrupt Identification
2 W FIFO control (INS16550 only)
3 R/W Data Format (Line Control)
4 R/W RS-232 (Modem) Control
5 R/W Line Status
6 R/W RS-232 (Modem) Status
7 R/W Not used.
For the standard PC ports (not DigiBoard ports), the UART registers are
based at 3F8h (COM1), 2F8h (COM2), 3E8h (COM3), and 2E8h (COM4). COM1 and
COM3 share interrupt request line IRQ4 while COM2 and COM4 share request
line IRQ3. This means that COM1 and COM3 can't be used concurrently.
Similarly for COM2 and COM4.
However, standard PC ports may be re-configured to use other UART addresses
and IRQ assignments. Refer to the SioPorts(), SioUART(), and SioIRQ()
functions.
If you have a DigiBoard PC/4 (or PC/8) installed, you will have 4 (or 8)
additional ports using INS16450 or INS16550 UARTS. The default DigiBoard
ports are located at 100h, 108h, 110h & 118h for the PC/4 continuing with
120h 128h, 130h & 138h for the PC/8. IRQ3 is the default for all ports.
Four sources of interrupts are possible with the 8250 and 16550: (1)
receiver error or BREAK, (2) receiver data ready, (3) ready to transmit, and
(4) RS232 input. These four sources of interrupts are summarized as
follows:
Source of Interrupt Action Required to Clear
Receiver error or BREAK. Read Line Status register.
Receiver data. Read data from data register.
Transmitter Buffer Empty. Write to data register or read IID reg.
RS232 Input. Read Modem Status register.
If you are not familiar with UARTS, several good books are available. Refer
to Chapter 6.0, Serial Communications chapter for recommendations.
Although a knowledge of the 8250/16450/16550 is not necessary to use PCL4W,
a general knowledge of the theory of asynchronous serial communications is
helpful.
PCL4W Users Manual Page 25
6.8 Register Summary
REG 0 : Data Register
Reading from the data register fetches the next input byte, once it is
ready. Writing to the data register transmits the byte written to it over
the serial line.
REG 1 : Interrupt Enable
The Interrupt Enable register enables each of four types of interrupts when
the appropriate bit is set to a one.
bit 3 : Enable interrupt on RS232 input.
bit 2 : Enable interrupt on receiver error or break.
bit 1 : Enable interrupt on transmitter buffer empty (TBE).
bit 0 : Enable interrupt on received data (RxRDY).
REG 2 : Interrupt Identification (IID)
Reading the Interrupt Identification (read only) register once an interrupt
has occurred identifies the interrupt as follows:
Bit 2 Bit 1 Bit 0 Priority Interrupt
0 0 1 none none
1 1 0 0 (high) Serialization or break.
1 0 0 1 Received data.
0 1 0 2 Transmitter Buffer Empty.
0 0 0 3 (low) RS232 Input.
In the INS16650, REG 2 (write only) is also the FIFO control register.
Writing bits 6 & 7 will set the FIFO trigger level (number of bytes received
before an interrupt is generated).
Bit 7 Bit 6 Trigger Bit 7 Bit 6 Trigger
0 0 1 byte 1 0 8 bytes
0 1 4 bytes 1 1 14 bytes
REG 3 : Line Control
RS232 line parameters are selected by writing to this register.
bit 7 : DLAB = 0
bit 6 : BREAK on(1), off(0).
bits 5-3: Parity None(000),ODD(001),EVEN(011),MARK(101),SPACE(111)
bit 2 : One stop bit(0), two stop bits(1).
bits 1-0: Data bits = 5 (00), 6(01), 7(10), 8(11).
When the Divisor Latch Access Bit (DLAB) is 1, registers 0 and 1 become the
LS and MS bytes of the Baud Rate Divisor registers.
Baud Divisor Baud Divisor Baud Divisor
300 0180 4800 0018 38400 0003
1200 0060 9600 000C 57600 0002
2400 0030 19200 0006 115200 0001
PCL4W Users Manual Page 26
REG 4 : Modem Control
RTS, DTR, loopback testing, and General Purpose Outputs #1 and #2 are
controlled by the Modem Control register as follows:
bit 4 : Enable local loopback.
bit 3 : Enable GP02. Necessary for 8250 interrupts.
bit 2 : Enable GP01.
bit 1 : Set / clear RTS.
bit 0 : Set / clear DTR.
REG 5 : Line Status
Reading the Line Status register provides status information as follows (1
for TRUE, 0 for FALSE) :
bit 6 : Transmitter Empty.
bit 5 : Transmitter Buffer Empty (TBE).
bit 4 : BREAK detect.
bit 3 : Framing error.
bit 2 : Parity error.
bit 1 : Overrun error.
bit 0 : Data Ready.
REG 6 : Modem Status
Reading the Modem Status register provides the following status information
(1 for TRUE, 0 for FALSE) :
bit 7 : DCD status.
bit 6 : RI status.
bit 5 : DSR status.
bit 4 : CTS status.
bit 3 : Delta DCD status.
bit 2 : Delta RI status.
bit 1 : Delta DSR status.
bit 0 : Delta CTS status.
The delta bits (bits 0 through 3) are set whenever one of the status bits
(bits 4 through 7) changes (from 0 to 1 or from 1 to 0) since the last time
the Modem Status register was read. Reading the Modem Status register clears
the delta bits.
REG 7 : Scratch Register
There is no function associated with register 7. It does not exist in
earlier versions of the 8250.
PCL4W Users Manual Page 27
7.0 Example Programs
The example programs can be built either using the command line makefile or
directly from your compiler's IDE (see section 3.6 "Using and IDE").
7.1 SIMPLE
SIMPLE is a very simple communications programming using PCL4W. Everything
that is typed on the keyboard is sent to the serial port, and everthing
incoming from the serial port is displayed on the screen.
Using the Microsoft command line compiler: NMAKE SIMPLE._M_
Using the Borland command line compiler: MAKER -fSIMPLE._B_
Using the Watcom command line compiler: WMAKE -f SIMPLE._W_
If you are using the Borland IDE, be sure and turn off LINKER case
sensitivies: Choose OPTIONS, PROJECTS, LINKER, GENERAL and turn off the
"case sensitive link" and "case sensitive exports & imports" boxes.
The SIMPLE makefiles use the small memory model. If a different memory model
is required, the Microsoft (or Borland) runtime library must also be
changed to match the memory model. No change is required for the PCL4W
library.
For example, to change the makefile from using the small memory model to
using the medium memory model, the following changes are necessary: For
Microsoft, change -AS to -AM and change SLIBCEW to MLIBCEW. For Borland,
change -sm to -mm and change C0WS, CWS, and MATHWS to C0WM, CWM, and MATHWM.
7.2 LOGIN
LOGIN is the same program as SIMPLE but with the addition of "Modem" on the
menu bar. Under "Modem", select "Start", then "Handshake" in order to send
an "AT" to the connected modem, or "Dial" to send a dial string to the modem
(which dials our user support BBS). Once the dial sequence is sent, the
program will wait for up to 60 seconds for the "CONNECT" string from the
modem. This wait can be terminated at any time by choosing "BREAK" under
"Modem".
To test LOGIN, you need a AT command set compatible modem and a BBS to call
up. LOGIN will dial our BBS at 205-880-9748, or edit the dial string in
LINE.C to call up a local BBS.
7.3 SELFTEST
SELFTEST performs a serial port I/O functionality test. A single port can be
tested if a loopback adapter is connected to the end of the serial cable.
Refer to LOOPBACK.DOC for an explanation of how to make a loopback adapter.
7.4 TERM
TERM is an example communications program suitable for calling bulletin
board systems (BBS).
TERM features modem initialization, hardware flow control, and state driven
file transfer using ASCII, XMODEM, and YMODEM, communications protocols.
TERM can be used to call up any bulletin board system, including the
MarshallSoft Computing BBS.
In an attempt to minimize the size of the shareware version of the PCL4W
library, the TERM program files are distributed as a separate file
(WTERMxx.ZIP, where xx is the current version). WTERMxx.ZIP can always be
downloaded from the MarshallSoft support BBS.
PCL4W Users Manual Page 28
8.0 Legal Issues
8.1 Registration
If you wish to register the PCL4W library, please send $75 plus $5 S&H ($10
outside of North America) to:
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815-4543
Multiple copies are available: $60 each for 2 to 5, $45 each for 5 to 10,
and $30 each for 20 or more. A site license is also available for $495
(includes 5 sets of printed documentation). We pay shipping.
We accept American Express, VISA, MasterCard, checks in US dollars drawn on
a US bank, International Postal Money Orders, purchase orders (POs) from
recognized US schools and companies listed in Dun & Bradstreet, and COD
(street address and phone number required) within the USA (plus a $4.50 COD
charge).
For credit card orders, be sure to include the account number, the
expiration date, the exact name on the card, and the complete card billing
address (the address to which the credit card bill is mailed).
You can also order PCL4W from The Public Software Library (PSL) with your
MC, Visa, AmEx, or Discover card by calling 800-242-4PSL (from overseas:
713-524-6394) or by FAX at 713-524-6398. THESE NUMBERS ARE FOR ORDERING
ONLY. The product number for PCL4W is 11171.
Print the file PCL4W.INV if an invoice is needed.
If you wish to update from an older version of PCL4W, send $25 plus $5 S&H
($10 outside of North America). Updates must be ordered directly from
MarshallSoft Computing.
The registered package includes:
o PCL4W Library w/o shareware screens.
o Assembler source code for the library.
o SCRIPT language V2.1 (compiler and interpreter).
o Laser printed Users and Reference Manuals.
o Telephone, BBS, and email support for one year.
The registered user will receive the latest version of PCL4W shipped by US
second day priority mail (packet airmail overseas). A 3.5" diskette is
provided unless a 5.25" diskette is requested.
All prices are guaranteed for one year from the release date as printed on
the title page.
PCL4W Users Manual Page 29
8.2 License
MarshallSoft Computing, Inc. grants the registered user of PCL4W the right
to use one copy of the PCL4W library (in object form) on a single computer
in the development of any software product (other than libraries such as
PCL4W). The user may not use the library on more than one computer at the
same time. The source code for the library (PCL4W.ASM) is copyrighted by
MarshallSoft Computing and may not be released in whole or in part. Products
developed using PCL4W may be distributed without any royalty.
8.3 Warranty
MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO THIS
SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE,
AND ALL SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER
MARSHALLSOFT COMPUTING, INC. NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE
CREATION, PRODUCTION, OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY
INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR
INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC. HAS
BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL
MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH DAMAGES EVER EXCEED
THE PRICE PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM
OF THE CLAIM. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY
AND PERFORMANCE OF THE SOFTWARE.
Some states do not allow the exclusion of the limit of liability for
consequential or incidental damages, so the above limitation may not apply
to you.
This agreement shall be governed by the laws of the State of Alabama and
shall inure to the benefit of Marshallsoft Computing, Inc. and any
successors, administrators, heirs and assigns. Any action or proceeding
brought by either party against the other arising out of or related to this
agreement shall be brought only in a STATE or FEDERAL COURT of competent
jurisdiction located in Madison County, Alabama. The parties hereby consent
to in personam jurisdiction of said courts.
PCL4W Users Manual Page 30
9.0 Summary
9.1 Revision History
Version 1.0: 1 February, 1994.
The initial release of PCL4W uses a considerable amount of the code from
version 4.0 of PCL4C (the DOS version of the comm library).
Version 1.1: August 1, 1994
o A flow control bug was fixed.
o COM11 through COM16 defined.
o Supports the BB1004, BB1008, and BB2016 BOCA boards.
o The new function SioGetDiv() was added.
o A script compiler & interpreter was added to the registration package.
Version 1.2: August 8, 1995
o Defined ports extended to 20.
o Support for all IRQs [IRQ0 to IRQ15].
o Bug in BREAK detection corrected.
o Bug in SioRxClear fixed.
o SioInfo also returns # interrupts.
Version 1.3: July 8, 1996
o SioRxFlush renamed SioRxClear.
o SioTxFlush renamed SioTxFlush.
o Added more choices in SioInfo.
o Added LOGIN & SELFTEST example programs.
o Simplified SIMPLE example program.
PCL4W Users Manual Page 31
9.2 Function Summary
Refer to the PCL4W Reference Manual (PCL4W.REF) for detailed information on
the communications and support functions. A one line summary of each
function follows:
+--------------+-----------------------------------------------------------+
| SioBaud | Sets the baud rate of the selected port. |
| SioBrkSig | Asserts, cancels, or detects BREAK signal. |
| SioCTS | Reads the Clear to Send (CTS) modem status bit. |
| SioDCD | Reads the Data Carrier Detect (DCD) modem status bit. |
| SioDone | Terminates further serial processing. |
| SioDSR | Reads the Data Set Ready (DSR) modem status bit. |
| SioDTR | Set, clear, or read the Data Terminal Ready (DTR) bit. |
| SioFIFO | Sets the interrupt level for the INS16550. |
| SioFlow | Enables / disables hardware flow control. |
| SioGetc | Reads the next character from the serial line. |
| SioGetDiv | Gets the baud rate divisor. |
| SioInfo | Returns library ver number, memory model, # interrupts |
| SioIRQ | Assigns an IRQ line to a port. |
| SioLine | Reads the line status register. |
| SioLoopBack | Performs a UART loopback test. |
| SioModem | Reads the modem status register. |
| SioParms | Sets parity, stop bits, and word length. |
| SioPorts | Sets # ports, 1st DigiBoard port & status register. |
| SioPutc | Transmit a character over a serial line. |
| SioRead | Reads any of 7 UART ports. |
| SioReset | Initialize a serial port for processing. |
| SioRI | Reads the Ring Indicator (RI) modem status bit. |
| SioRTS | Sets, clears, or reads the Request to Send (RTS) line. |
| SioRxBuf | Sets up receive buffer. |
| SioRxClear | Clears the receive buffer. |
| SioRxQue | Returns the number of characters in the receive queue. |
| SioTxBuf | Sets up transmit buffer. |
| SioTxClear | Clears the transmit buffer. |
| SioTxQue | Returns the number of characters in the transmit queue. |
| SioUART | Sets the UART base address. |
| SioUnGetc | "Un-gets" (puts back) a specified character. |
+--------------+-----+-----------------------------------------------------+
PCL4W Users Manual Page 32
9.3 Further Reading
The best way to learn about serial communications is to read a good book on
the subject. Several good texts are available. Two that I like are:
(1) C Programmers's Guide to Serial Communications by Joe Campbell (SAMS)
(2) Mastering Serial Communications by Peter Gofton (SYBEX).
10.0 Other MarshallSoft Computing Products
The following shareware libraries are also available from MarshallSoft
Computing. They can be registered directly through us.
10.1 The Personal Communications Library for C/C++
The Personal Communications Library for the C Language (PCL4C) is a DOS
based asynchronous communications library designed for experienced software
developers programming in C. Four compilers are supported: Microsoft
Optimizing C, Microsoft Quick C, Borland Turbo C, and MIX Power C. An IBM
PC/XT/AT or compatible is required. PCL4C is the DOS equivalent of PCL4W.
The Personal Communications Library for C (PCL4C) is available for $75 plus
$5 S&H ($10 S&H overseas). PCL4C and PCL4W can be ordered together for $120
plus $5 S&H ($10 overseas).
10.2 Libraries for Other Languages
We also have communications libraries for Turbo Pascal, Visual Basic (DOS),
and PowerBASIC. A Visual BASIC library for Windows is also available.
PCL4W Users Manual Page 33
